home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kjanuswidget.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  22.0 KB  |  607 lines
  1. /*  This file is part of the KDE Libraries
  2.  *  Copyright (C) 1999-2000 Espen Sand (espen@kde.org)
  3.  *
  4.  *  This library is free software; you can redistribute it and/or
  5.  *  modify it under the terms of the GNU Library General Public
  6.  *  License as published by the Free Software Foundation; either
  7.  *  version 2 of the License, or (at your option) any later version.
  8.  *
  9.  *  This library is distributed in the hope that it will be useful,
  10.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.  *  Library General Public License for more details.
  13.  *
  14.  *  You should have received a copy of the GNU Library General Public License
  15.  *  along with this library; see the file COPYING.LIB.  If not, write to
  16.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.  *  Boston, MA 02110-1301, USA.
  18.  */
  19.  
  20. #ifndef _KJANUS_WIDGET_H_
  21. #define _KJANUS_WIDGET_H_
  22.  
  23. #include <qptrlist.h>
  24. #include <qpixmap.h>
  25. #include <qsplitter.h>
  26.  
  27. #include <klistbox.h>
  28. #include <qstringlist.h>
  29. #include <qmap.h>
  30.  
  31. class KListView;
  32.  
  33. class QGrid;
  34. class QHBox;
  35. class QLabel;
  36. class QTabWidget;
  37. class QVBox;
  38. class QWidgetStack;
  39. class KSeparator;
  40. class QListViewItem;
  41. class KGuiItem;
  42.  
  43. /**
  44.  * @short Easy to use widget with many layouts
  45.  *
  46.  * Provides a number of ready to use layouts (faces). It is used
  47.  * as an internal widget in KDialogBase, but can also used as a
  48.  * widget of its own.
  49.  *
  50.  * This class provides KJanusWidget::TreeList, KJanusWidget::IconList,
  51.  * KJanusWidget::Tabbed, KJanusWidget::Plain and KJanusWidget::Swallow layouts.
  52.  *
  53.  * For all modes it is important that you specify the QWidget::minimumSize()
  54.  * on the page, plain widget or the swallowed widget. If you use a QLayout
  55.  * on the page, plain widget or the swallowed widget this will be taken care
  56.  * of automatically. The size is used when the KJanusWidget determines its
  57.  * own minimum size. You get the minimum size by using the
  58.  * minimumSizeHint() or sizeHint() methods.
  59.  *
  60.  * Pages that have been added in TreeList, IconList or Tabbed mode can be
  61.  * removed by simply deleting the page. However, it would be preferable to use
  62.  * the QObject::deleteLater() function on the page as the main event loop
  63.  * may have optimized UI update events of the page by scheduling them for later.
  64.  *
  65.  * @author Espen Sand (espen@kde.org)
  66.  */
  67. class KDEUI_EXPORT KJanusWidget : public QWidget
  68. {
  69.   Q_OBJECT
  70.  
  71.   private:
  72.     class IconListBox : public KListBox
  73.     {
  74.       public:
  75.         IconListBox( QWidget *parent=0, const char *name=0, WFlags f=0 );
  76.     void updateMinimumHeight();
  77.     void updateWidth();
  78.     void invalidateHeight();
  79.     void invalidateWidth();
  80.     void setShowAll( bool showAll );
  81.  
  82.       private:
  83.     bool mShowAll;
  84.     bool mHeightValid;
  85.     bool mWidthValid;
  86.     };
  87.  
  88.   public:
  89.     enum Face
  90.     {
  91.       /**
  92.        * The TreeList face provides a list in the left area and pages in the
  93.        * right. The area are separated by a movable splitter. The style is somewhat
  94.        * similar to the layout in the Control Center. A page is raised by
  95.        * selecting the corresponding tree list item.
  96.        */
  97.       TreeList = 0,
  98.       /** The Tabbed face is a common tabbed widget. The procedure for creating a
  99.        * page is similar for creating a TreeList. This has the advantage that if
  100.        * your widget contain too many pages it is trivial to convert it into a
  101.        * TreeList. Just change the face in the KJanusWidget constructor to
  102.        * KJanusWidget::TreeList and you have a tree list layout instead.
  103.        */
  104.       Tabbed,
  105.       /**
  106.        * The Plain face provides an empty widget (QFrame) where you can place your
  107.        * widgets. The KJanusWidget makes no assumptions regarding the contents so
  108.        * you are free to add whatever you want.
  109.        */
  110.       Plain,
  111.       /**
  112.        * The Swallow face is provided in order to simplify the usage of existing
  113.        * widgets and to allow changing the visible widget. You specify the widget
  114.        * to be displayed by setSwallowedWidget(). Your widget will be
  115.        * reparented inside the widget. You can specify a Null (0) widget. A empty
  116.        * space is then displayed.
  117.        */
  118.       Swallow,
  119.       /**
  120.        * The IconList face provides an icon list in the left area and pages in the
  121.        * right. For each entry the Icon is on top with the text below. The style
  122.        * is somewhat similar to the layout of the Eudora configuation dialog box.
  123.        * A page is raised by selecting the corresponding icon list item. The
  124.        * preferred icon size is 32x32 pixels.
  125.        */
  126.       IconList
  127.     };
  128.  
  129.   public:
  130.  
  131.     /**
  132.      * Constructor where you specify the face.
  133.      *
  134.      * @param parent Parent of the widget.
  135.      * @param name Widget name.
  136.      * @param face The kind of dialog, Use TreeList, Tabbed, Plain or
  137.      * Swallow.
  138.      */
  139.     KJanusWidget( QWidget *parent=0, const char *name=0, int face=Plain );
  140.  
  141.     /**
  142.      * Destructor.
  143.      */
  144.     ~KJanusWidget();
  145.  
  146.     /**
  147.      * Raises the page which was added by addPage().
  148.      *
  149.      * @param index The index of the page you want to raise.
  150.      */
  151.     virtual bool showPage( int index );
  152.  
  153.     /**
  154.      * Returns the index of the page that are currently displayed.
  155.      *
  156.      * @return The index or -1 if the face is not Tabbed, TreeList or
  157.      *         IconList.
  158.      */
  159.     virtual int  activePageIndex() const;
  160.  
  161.     /**
  162.      * Use this to verify
  163.      * that no memory allocation failed.
  164.      *
  165.      * @return true if the widget was properly created.
  166.      */
  167.     virtual bool isValid() const;
  168.  
  169.     /**
  170.      * Returns the face type.
  171.      *
  172.      * @return The face type.
  173.      */
  174.     virtual int face() const;
  175.  
  176.     /**
  177.      * Returns the minimum size that must be made available for the widget
  178.      * so that UIs can be displayed properly
  179.      *
  180.      * @return The minimum size.
  181.      */
  182.     virtual QSize minimumSizeHint() const;
  183.  
  184.     /**
  185.      * Returns the recommended size for the widget in order to be displayed
  186.      * properly.
  187.      *
  188.      * @return The recommended size.
  189.      */
  190.     virtual QSize sizeHint() const;
  191.  
  192.     /**
  193.      * Returns the empty widget that is available in Plain mode.
  194.      *
  195.      * @return The widget or 0 if the face in not Plain.
  196.      */
  197.     virtual QFrame *plainPage();
  198.  
  199.     /**
  200.      * Add a new page when the class is used in TreeList, IconList or Tabbed
  201.      * mode. The returned widget is empty and you must add your widgets
  202.      * as children to this widget. In most cases you must create a layout
  203.      * manager and associate it with this widget as well.
  204.      *
  205.      * Deleting the returned frame will cause the listitem or tab to be
  206.      * removed (you can re-add a page with the same name later.
  207.      *
  208.      * @param item String used in the list or Tab item.
  209.      * @param header A longer string used in TreeList and IconList mode to
  210.      *        describe the contents of a page. If empty, the item string
  211.      *        will be used instead.
  212.      * @param pixmap Used in IconList mode or in TreeList mode. You should
  213.      *        prefer a pixmap with size 32x32 pixels.
  214.      *
  215.      * @return The empty page or 0 if the face is not TreeList, IconList or
  216.      *         Tabbed.
  217.      */
  218.     virtual QFrame *addPage(const QString &item,const QString &header=QString::null,
  219.             const QPixmap &pixmap=QPixmap() );
  220.  
  221.     /**
  222.      * This is like addPage just above, with the difference that the first
  223.      * element is a list of strings. These strings are used to form a path
  224.      * of folders down to the given page. The initial elements are names
  225.      * for the folders, while the last element is the name of the page.
  226.      * Note: This does yet only work for the TreeList face. Later this may
  227.      * be added for the IconList face too. In other faces than the
  228.      * TreeList, all the strings except the last one is ignored.
  229.         * Deleting the returned frame will cause the listitem or tab to be
  230.      * removed (you can re-add a page with the same name later.
  231.      *
  232.      * Deleting the returned frame will cause the listitem or tab to be
  233.      * removed (you can re-add a page with the same name later.
  234.      **/
  235.      virtual QFrame *addPage(const QStringList &items, const QString &header=QString::null,
  236.             const QPixmap &pixmap=QPixmap() );
  237.  
  238.     /**
  239.      * Add a new page when the class is used in TreeList, IconList or Tabbed
  240.      * mode. The returned widget is empty and you must add your widgets
  241.      * as children to this widget. The returned widget is a QVBox
  242.      * so it contains a QVBoxLayout layout that lines up the child widgets
  243.      * are vertically.
  244.      *
  245.      * Deleting the returned frame will cause the listitem or tab to be
  246.      * removed (you can re-add a page with the same name later.
  247.      *
  248.      * @param item String used in the list or Tab item.
  249.      * @param header A longer string used in TreeList and IconList mode to
  250.      *        describe the contents of a page. If empty, the item string
  251.      *        will be used instead.
  252.      * @param pixmap Used in IconList mode or in TreeList mode. You should
  253.      *        prefer a pixmap with size 32x32 pixels.
  254.      *
  255.      * @return The empty page or 0 if the face is not TreeList, IconList or
  256.      *         Tabbed.  */
  257.     virtual QVBox *addVBoxPage( const QString &item,
  258.             const QString &header=QString::null,
  259.             const QPixmap &pixmap=QPixmap() );
  260.  
  261.     /**
  262.      * This is like addVBoxPage just above, with the difference that the first
  263.      * element is a list of strings. These strings are used to form a path
  264.      * of folders down to the given page. The initial elements are names
  265.      * for the folders, while the last element is the name of the page.
  266.      * Note: This does yet only work for the TreeList face. Later this may
  267.      * be added for the IconList face too. In other faces than the
  268.      * TreeList, all the strings except the last one is ignored.
  269.      *
  270.      * Deleting the returned frame will cause the listitem or tab to be
  271.      * removed (you can re-add a page with the same name later.
  272.      **/
  273.     virtual QVBox *addVBoxPage( const QStringList &items,
  274.             const QString &header=QString::null,
  275.             const QPixmap &pixmap=QPixmap() );
  276.  
  277.     /**
  278.      * Add a new page when the class is used in TreeList, IconList or Tabbed
  279.      * mode. The returned widget is empty and you must add your widgets
  280.      * as children to this widget. The returned widget is a QHBox
  281.      * so it contains a QHBoxLayout layout that lines up the child widgets
  282.      * are horizontally.
  283.      *
  284.      * Deleting the returned frame will cause the listitem or tab to be
  285.      * removed (you can re-add a page with the same name later.
  286.      *
  287.      * @param itemName String used in the list or Tab item.
  288.      * @param header A longer string used in TreeList and IconList mode to
  289.      *        describe the contents of a page. If empty, the item string
  290.      *        will be used instead.
  291.      * @param pixmap Used in IconList mode or in TreeList mode. You should
  292.      *        prefer a pixmap with size 32x32 pixels.
  293.      *
  294.      * @return The empty page or 0 if the face is not TreeList, IconList or
  295.      *         Tabbed.
  296.      */
  297.     virtual QHBox *addHBoxPage( const QString &itemName,
  298.             const QString &header=QString::null,
  299.             const QPixmap &pixmap=QPixmap() );
  300.  
  301.     /**
  302.      * This is like addHBoxPage just above, with the difference that the first
  303.      * element is a list of strings. These strings are used to form a path
  304.      * of folders down to the given page. The initial elements are names
  305.      * for the folders, while the last element is the name of the page.
  306.      * Note: This does yet only work for the TreeList face. Later this may
  307.      * be added for the IconList face too. In other faces than the
  308.      * TreeList, all the strings except the last one is ignored.
  309.      *
  310.      * Deleting the returned frame will cause the listitem or tab to be
  311.      * removed (you can re-add a page with the same name later.
  312.      **/
  313.     virtual QHBox *addHBoxPage( const QStringList &items,
  314.             const QString &header=QString::null,
  315.             const QPixmap &pixmap=QPixmap() );
  316.  
  317.     /**
  318.      * Add a new page when the class is used in either TreeList or Tabbed
  319.      * mode. The returned widget is empty and you must add your widgets
  320.      * as children to this widget. The returned widget is a QGrid
  321.      * so it contains a QGridLayout layout that places up the child widgets
  322.      * in a grid.
  323.      *
  324.      * Deleting the returned frame will cause the listitem or tab to be
  325.      * removed (you can re-add a page with the same name later.
  326.      *
  327.      * @param n Specifies the number of columns if 'dir' is QGrid::Horizontal
  328.      *          or the number of rows if 'dir' is QGrid::Vertical.
  329.      * @param dir Can be QGrid::Horizontal or QGrid::Vertical.
  330.      * @param itemName String used in the list or Tab item.
  331.      * @param header A longer string used in TreeList and IconList mode to
  332.      *        describe the contents of a page. If empty, the item string
  333.      *        will be used instead.
  334.      * @param pixmap Used in IconList mode or in TreeList mode. You should
  335.      *        prefer a pixmap with size 32x32 pixels.
  336.      *
  337.      * @return The empty page or 0 if the face is not TreeList, IconList or
  338.      *         Tabbed.
  339.      */
  340.     virtual QGrid *addGridPage( int n, Orientation dir,
  341.             const QString &itemName,
  342.             const QString &header=QString::null,
  343.             const QPixmap &pixmap=QPixmap() );
  344.  
  345.     /**
  346.      * This is like addGridPage just above, with the difference that the first
  347.      * element is a list of strings. These strings are used to form a path
  348.      * of folders down to the given page. The initial elements are names
  349.      * for the folders, while the last element is the name of the page.
  350.      * Note: This does yet only work for the TreeList face. Later this may
  351.      * be added for the IconList face too. In other faces than the
  352.      * TreeList, all the strings except the last one is ignored.
  353.      *
  354.      * Deleting the returned frame will cause the listitem or tab to be
  355.      * removed (you can re-add a page with the same name later.
  356.      **/
  357.     virtual QGrid *addGridPage( int n, Orientation dir,
  358.             const QStringList &items,
  359.             const QString &header=QString::null,
  360.             const QPixmap &pixmap=QPixmap() );
  361.  
  362.     /**
  363.      * @short Removes a page created with addPage, addVBoxPage,
  364.      * addHBoxPage or addGridPage. If the page has already
  365.      * been deleted or has already been removed, nothing happens. The widget
  366.      * itself is not deleted.
  367.      *
  368.      * @param page The widget returned by addPage , addVBoxPage ,
  369.      * addHBoxPage or addGridPage .
  370.      */
  371.     void removePage( QWidget *page );
  372.  
  373.  
  374.     /**
  375.      * Returns the index of a page created with addPage ,
  376.      * addVBoxPage , addHBoxPage or addGridPage .
  377.      * You can can compare this index with the value returned from
  378.      * activePageIndex if you need to do some page specific actions
  379.      * in your code.
  380.      *
  381.      * The returned index will never change so you can safely use this
  382.      * function once and save the value.
  383.      *
  384.      * @param widget The widget returned by addPage , addVBoxPage ,
  385.      * addHBoxPage or addGridPage .
  386.      *
  387.      * @return The index or -1 if the face is not Tabbed, TreeList or
  388.      *         IconList
  389.      */
  390.     virtual int pageIndex( QWidget *widget ) const;
  391.  
  392.     /**
  393.      * Defines the widget to be swallowed.
  394.      *
  395.      * This method can be used several
  396.      * times. Only the latest defined widget will be shown.
  397.      *
  398.      * @param widget The widget to be swallowed. If 0, then an empty rectangle
  399.      * is displayed.
  400.      */
  401.     virtual bool setSwallowedWidget( QWidget *widget );
  402.  
  403.     /**
  404.      * This function has only effect in TreeList mode.
  405.      *
  406.      * Defines how the tree list is resized when the widget is resized
  407.      * horizontally. By default the tree list keeps its width when the
  408.      * widget becomes wider.
  409.      *
  410.      * @param state The resize mode. If false (default) the TreeList keeps
  411.      *              its current width when the widget becomes wider.
  412.      */
  413.     virtual void setTreeListAutoResize( bool state );
  414.  
  415.     /**
  416.      * This function has only effect in TreeList mode.
  417.      *
  418.      * This tells the widgets whether the icons given in the addPage,
  419.      * addVBoxPage, addHBoxPage, or addGridPage methods should
  420.      * be shown in the TreeList.
  421.      *
  422.      * Note: This method must be called before calling any of the methods
  423.      * which add icons to the page.
  424.      *
  425.      * @param state If true the icons are shown.
  426.      **/
  427.     virtual void setShowIconsInTreeList(bool state);
  428.  
  429.     /**
  430.      * This function has only effect in TreeList mode.
  431.      *
  432.      * This tells the widgets whether the root should be decorated.
  433.      * For details see QListView::setRootIsDecorated
  434.      *
  435.      * @param state Root will be decorated if true.
  436.      **/
  437.     virtual void setRootIsDecorated( bool state );
  438.  
  439.     /**
  440.      * This function has only effect in TreeList mode.
  441.      *
  442.      * This tells the TreeList to unfold the whole tree so that all entries
  443.      * are visible.
  444.      *
  445.      * If the list is empty when you call this method newly created entries
  446.      * will not automatically be opened. If the @p persist flag is set opened
  447.      * entries cannot be closed again, though.
  448.      *
  449.      * @param persist If true the tree always stays unfolded.
  450.      * @since 3.2
  451.      */
  452.     /*virtual*/ void unfoldTreeList( bool persist = false ); //### KDE4 BIC add virtual
  453.  
  454.     /**
  455.      * Add a widget at the bottom of the TreeList/IconList.
  456.      *
  457.      * @param widget  The widget to be added. It will be reparented into the
  458.      *                KJanusWidget, therefor it will be deleted with the
  459.      *                KJanusWidget, too. To be on the save side just don't keep
  460.      *                the pointer to this widget.
  461.      */
  462.     /*virtual*/ void addWidgetBelowList( QWidget * widget ); // ### KDE4
  463.  
  464.     /**
  465.      * Add a button at the bottom of the TreeList/IconList.
  466.      *
  467.      * @param text     The text on the PushButton.
  468.      * @param recv     The object that is to receive the signal when the button
  469.      *                 is clicked.
  470.      * @param slot     The slot to connect to the clicked signal of the button.
  471.      *
  472.      * @since 3.2
  473.      */
  474.     /*virtual*/ void addButtonBelowList( const QString & text, QObject * recv,
  475.                     const char * slot ); //### KDE4
  476.  
  477.     /**
  478.      * The same as the above function, but with a KGuiItem providing the text
  479.      * and icon for the button at the bottom of the TreeList/IconList.
  480.      *
  481.      * @param guiitem  The text and icon on the PushButton.
  482.      * @param recv     The object that is to receive the signal when the button
  483.      *                 is clicked.
  484.      * @param slot     The slot to connect to the clicked signal of the button.
  485.      *
  486.      * @since 3.2
  487.      */
  488.     /*virtual*/ void addButtonBelowList( const KGuiItem & guiitem, QObject *
  489.                     recv, const char * slot ); //### KDE4
  490.  
  491.     /**
  492.      * This function has only effect in IconList mode.
  493.      *
  494.      * Defines how the icon list widget is displayed. By default it is
  495.      * the widgets in the pages that decide the minimum height
  496.      * of the toplevel widget. A vertical scrollbar can be used in
  497.      * the icon list area.
  498.      *
  499.      * @param state The visibility mode. If true, the minimum height is
  500.      *        adjusted so that every icon in the list is visible at the
  501.      *        same time. The vertical scrollbar will never be visible.
  502.      */
  503.     virtual void setIconListAllVisible( bool state );
  504.  
  505.     /**
  506.      * Sets the icon used in TreeList Mode for the given path.
  507.      * @param path The path for which this icon should be shown.
  508.      * @param pixmap The icon used.
  509.      **/
  510.     virtual void setFolderIcon(const QStringList &path, const QPixmap &pixmap);
  511.     /**
  512.      * Returns the title string associated with a page index in TreeList or IconList mode.
  513.      * @param index The index of the page or null if there is no such page.
  514.      * @see pageIndex()
  515.      * @since 3.2
  516.      */
  517.     /*virtual*/ QString pageTitle(int index) const;
  518.     /**
  519.      * Returns the page widget associated with a page index or null if there is
  520.      * no such page.
  521.      * @param index The index of the page.
  522.      * @see pageIndex()
  523.      * @since 3.2
  524.      */
  525.     /*virtual*/ QWidget *pageWidget(int index) const;
  526.  
  527.   signals:
  528.     /**
  529.      * This signal is emitted whenever the current page changes.
  530.      * @param page the new page. 
  531.      * @since 3.4
  532.      */
  533.     void aboutToShowPage(QWidget *page);
  534.  
  535.   public slots:
  536.     /**
  537.      * Give the keyboard input focus to the widget.
  538.      */
  539.     virtual void setFocus();
  540.  
  541.   protected:
  542.     /**
  543.      * Reimplemented to handle the splitter width when the the face
  544.      * is TreeList
  545.      */
  546.     virtual void showEvent( QShowEvent * );
  547.  
  548.     /**
  549.      * This function is used internally when in IconList mode. If you
  550.      * reimplement this class a make your own event filter, make sure to
  551.      * call this function from your filter.
  552.      *
  553.      * @param o Object that has received an event.
  554.      * @param e The event.
  555.      */
  556.     virtual bool eventFilter( QObject *o, QEvent *e );
  557.  
  558.   private slots:
  559.     bool slotShowPage();
  560.     void slotFontChanged();
  561.     void slotItemClicked(QListViewItem *it);
  562.     void pageGone(QObject *obj); // signal from the added page's "destroyed" signal
  563.     void slotReopen(QListViewItem *item);
  564.  
  565.   protected:
  566.     bool showPage( QWidget *w );
  567.     void addPageWidget( QFrame *page, const QStringList &items,
  568.             const QString &header, const QPixmap &pixmap );
  569.     void InsertTreeListItem(const QStringList &items, const QPixmap &pixmap, QFrame *page);
  570.     QWidget *FindParent();
  571.  
  572.   private:
  573.     bool mValid;
  574.  
  575.     // Obsolete members. Remove in KDE 4.
  576.     QPtrList<QWidget> *mPageList;
  577.     QStringList *mTitleList;
  578.  
  579.     int          mFace;
  580.     KListView    *mTreeList;
  581.     IconListBox  *mIconList;
  582.     QWidgetStack *mPageStack;
  583.     QLabel       *mTitleLabel;
  584.     QTabWidget   *mTabControl;
  585.     QFrame       *mPlainPage;
  586.     QWidget      *mSwallowPage;
  587.     QWidget      *mActivePageWidget;
  588.     KSeparator   *mTitleSep;
  589.     QSplitter::ResizeMode mTreeListResizeMode;
  590.     bool         mShowIconsInTreeList;
  591.     QMap<QListViewItem *, QWidget *> mTreeListToPageStack;
  592.     QMap<QListBoxItem *, QWidget *> mIconListToPageStack;
  593.     QMap<QString, QPixmap> mFolderIconMap;
  594.     QMap<QString, QStringList> mChildrenNames;
  595.     QMap<QString, QWidget *> mChildPages;
  596.  
  597.   public:
  598.     class IconListItem;
  599.   protected:
  600.     virtual void virtual_hook( int id, void* data );
  601.   private:
  602.     class KJanusWidgetPrivate;
  603.     KJanusWidgetPrivate *d;
  604. };
  605.  
  606. #endif
  607.